

<!doctype html>

<html lang="en" data-content_root="../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>skidl.utilities module &#8212; SKiDL 1.2.2 documentation</title>
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
    <link rel="stylesheet" type="text/css" href="../_static/bizstyle.css?v=a66e137f" />
    
    <script src="../_static/documentation_options.js?v=fd7cadf9"></script>
    <script src="../_static/doctools.js?v=9a2dae69"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/bizstyle.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <!--[if lt IE 9]>
    <script src="_static/css3-mediaqueries.js"></script>
    <![endif]-->
  </head><body>
    <h1 id="site-title"><a href="../../../"><img src="../../../images/slim_banner.png" width="100%"></a></h1>
    
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">SKiDL 1.2.2 documentation</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">skidl.utilities module</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="module-skidl.utilities">
<span id="skidl-utilities-module"></span><h1>skidl.utilities module<a class="headerlink" href="#module-skidl.utilities" title="Link to this heading">¶</a></h1>
<p>Utility functions used by the rest of SKiDL.</p>
<dl class="py class">
<dt class="sig sig-object py" id="skidl.utilities.Rgx">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">Rgx</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#Rgx"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.Rgx" title="Link to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3.11/library/stdtypes.html#str" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a></p>
<p>Same as a string but the class makes it recognizable as as a regular expression.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="skidl.utilities.TriggerDict">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">TriggerDict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#TriggerDict"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.TriggerDict" title="Link to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3.11/library/stdtypes.html#dict" title="(in Python v3.11)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a></p>
<p>This dict triggers a function when one of its entries changes.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.add_quotes">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">add_quotes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#add_quotes"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.add_quotes" title="Link to this definition">¶</a></dt>
<dd><p>Return string with added quotes if it contains whitespace or parens.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.add_unique_attr">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">add_unique_attr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">check_dup</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#add_unique_attr"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.add_unique_attr" title="Link to this definition">¶</a></dt>
<dd><p>Create an attribute if the attribute name isn’t already used.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.cnvt_to_var_name">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">cnvt_to_var_name</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#cnvt_to_var_name"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.cnvt_to_var_name" title="Link to this definition">¶</a></dt>
<dd><p>Convert a string to a legal Python variable name and return it.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.debug_trace">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">debug_trace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#debug_trace"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.debug_trace" title="Link to this definition">¶</a></dt>
<dd><p>Decorator to print tracing info when debugging execution.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.expand_buses">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">expand_buses</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pins_nets_buses</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#expand_buses"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.expand_buses" title="Link to this definition">¶</a></dt>
<dd><p>Take list of pins, nets, and buses and return a list of only pins and nets.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.expand_indices">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">expand_indices</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">slice_min</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">slice_max</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">match_regex</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">indices</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#expand_indices"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.expand_indices" title="Link to this definition">¶</a></dt>
<dd><p>Expand a list of indices into a list of integers and strings.</p>
<p>This function takes the indices used to select pins of parts and
lines of buses and returns a flat list of numbers and strings.
String and integer indices are put in the list unchanged, but
slices are expanded into a list of integers before entering the
final list.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>slice_min</strong> – The minimum possible index.</p></li>
<li><p><strong>slice_max</strong> – The maximum possible index (used for slice indices).</p></li>
<li><p><strong>match_regex</strong> – If true,</p></li>
<li><p><strong>indices</strong> – A list of indices made up of numbers, slices, text strings.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A linear list of all the indices made up only of numbers and strings.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.export_to_all">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">export_to_all</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#export_to_all"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.export_to_all" title="Link to this definition">¶</a></dt>
<dd><p>Add a function to the __all__ list of this module.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>fn</strong> (<em>function</em>) – The function to be added to the __all__ list of this module.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>The function that was passed in.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>function</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.filter_list">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">filter_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lst</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">criteria</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#filter_list"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.filter_list" title="Link to this definition">¶</a></dt>
<dd><p>Return a list of objects whose attributes match a set of criteria.</p>
<p>Return a list of objects extracted from a list whose attributes match a
set of criteria. The match is done using regular expressions.
Example: filter_list(pins, name=’io[0-9]+’, direction=’bidir’) will
return all the bidirectional pins of the component that have pin names
starting with ‘io’ followed by a number (e.g., ‘IO45’).</p>
<p>If an attribute of the lst object is a list or tuple, each entry in the
list/tuple will be checked for a match. Only one entry needs to match to
consider the entire attribute a match. This feature is useful when
searching for objects that contain a list of aliases, such as Part objects.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>lst</strong> – The list from which objects will be extracted.</p>
</dd>
</dl>
<dl class="simple">
<dt>Keywords Args:</dt><dd><dl class="simple">
<dt>criteria: Keyword-argument pairs. The keyword specifies the attribute</dt><dd><p>name while the argument contains the desired value of the attribute.
Regardless of what type the argument is, it is always compared as if
it was a string. The argument can also be a regular expression that
must match the entire string created from the attribute of the list
object.</p>
</dd>
</dl>
</dd>
</dl>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>A list of objects whose attributes match <em>all</em> the criteria.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.find_and_open_file">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">find_and_open_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">paths</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ext</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_failure</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exclude_binary</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">descend</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#find_and_open_file"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.find_and_open_file" title="Link to this definition">¶</a></dt>
<dd><p>Search for a file in list of paths, open it and return file pointer and full file name.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>filename</strong> – Base file name (e.g., “my_file”).</p></li>
<li><p><strong>paths</strong> – List of paths to search for the file.</p></li>
<li><p><strong>ext</strong> – The extension for the file (e.g., “.txt”).</p></li>
<li><p><strong>allow_failure</strong> – If false, failure to find file raises and exception.</p></li>
<li><p><strong>exclude_binary</strong> – If true, skip files that contain binary data.</p></li>
<li><p><strong>descend</strong> – If 0, don’t search lower-level directories. If positive, search
that many levels down for the file. If negative, descend into
subdirectories withcurrent_level limit.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>File pointer and file name or None, None if file could not be opened.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.find_and_read_file">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">find_and_read_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">paths</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ext</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_failure</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exclude_binary</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">descend</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#find_and_read_file"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.find_and_read_file" title="Link to this definition">¶</a></dt>
<dd><p>Search for a file in list of paths, open it and return its contents.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>filename</strong> – Base file name (e.g., “my_file”).</p></li>
<li><p><strong>paths</strong> – List of paths to search for the file.</p></li>
<li><p><strong>ext</strong> – The extension for the file (e.g., “.txt”).</p></li>
<li><p><strong>allow_failure</strong> – If false, failure to find file raises and exception.</p></li>
<li><p><strong>exclude_binary</strong> – If true, skip files that contain binary data.</p></li>
<li><p><strong>descend</strong> – If 0, don’t search lower-level directories. If positive, search
that many levels down for the file. If negative, descend into
subdirectories withcurrent_level limit.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>File contents and file name or None, None if file could not be opened.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.find_num_copies">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">find_num_copies</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">attribs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#find_num_copies"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.find_num_copies" title="Link to this definition">¶</a></dt>
<dd><p>Return the number of copies to make based on the number of attribute values.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>attribs</strong> – Dict of Keyword/Value pairs for setting object attributes.
If the value is a scalar, then the number of copies is one.
If the value is a list/tuple, the number of copies is the
length of the list/tuple.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>The length of the longest value in the dict of attributes.</p>
</dd>
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>Exception if there are two</strong><strong> or </strong><strong>more list/tuple values with different</strong> – </p></li>
<li><p><strong>lengths that are greater than 1.</strong><strong> (</strong><strong>All attribute values must be scalars</strong> – </p></li>
<li><p><strong>or lists/tuples</strong><strong> of </strong><strong>the same length.</strong><strong>)</strong> – </p></li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.flatten">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">flatten</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">nested_list</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#flatten"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.flatten" title="Link to this definition">¶</a></dt>
<dd><p>Return a flattened list of items from a nested list.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.from_iadd">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">from_iadd</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">objs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#from_iadd"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.from_iadd" title="Link to this definition">¶</a></dt>
<dd><p>Return True if one or more objects have attribute iadd_flag set to True.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.fullmatch">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">fullmatch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">regex</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#fullmatch"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.fullmatch" title="Link to this definition">¶</a></dt>
<dd><p>Emulate python-3.4 re.fullmatch().</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.get_unique_name">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">get_unique_name</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lst</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attrib</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prefix</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initial</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#get_unique_name"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.get_unique_name" title="Link to this definition">¶</a></dt>
<dd><p>Return a name that doesn’t collide with another in a list.</p>
<p>This subrcurrent_leveline is used to generate unique part references (e.g., “R12”)
or unique net names (e.g., “N$5”).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>lst</strong> – The list of objects containing names.</p></li>
<li><p><strong>attrib</strong> – The attribute in each object containing the name.</p></li>
<li><p><strong>prefix</strong> – The prefix attached to each name.</p></li>
<li><p><strong>initial</strong> – The initial setting of the name (can be None or empty string).</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A string containing the unique name.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.is_binary_file">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">is_binary_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#is_binary_file"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.is_binary_file" title="Link to this definition">¶</a></dt>
<dd><p>Return true if a file contains binary (non-text) characters.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.list_or_scalar">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">list_or_scalar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lst</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#list_or_scalar"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.list_or_scalar" title="Link to this definition">¶</a></dt>
<dd><p>Return a list if passed a multi-element list, otherwise return a single scalar.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>lst</strong> – Either a list or a scalar.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><ul class="simple">
<li><p>A list if passed a multi-element list.</p></li>
<li><p>The list element if passed a single-element list.</p></li>
<li><p>None if passed an empty list.</p></li>
<li><p>A scalar if passed a scalar.</p></li>
</ul>
</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.merge_dicts">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">merge_dicts</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dct</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">merge_dct</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#merge_dicts"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.merge_dicts" title="Link to this definition">¶</a></dt>
<dd><p>Dict merge that recurses through both dicts and updates keys.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>dct</strong> – The dict that will be updated.</p></li>
<li><p><strong>merge_dct</strong> – The dict whose values will be inserted into dct.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Nothing.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.norecurse">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">norecurse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#norecurse"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.norecurse" title="Link to this definition">¶</a></dt>
<dd><p>Decorator that keeps a function from recursively calling itself.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>f</strong> (<em>function</em>)</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.num_to_chars">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">num_to_chars</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">num</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#num_to_chars"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.num_to_chars" title="Link to this definition">¶</a></dt>
<dd><p>Return a string like ‘AB’ when given a number like 28.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.opened">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">opened</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f_or_fn</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#opened"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.opened" title="Link to this definition">¶</a></dt>
<dd><p>Yields an opened file or file-like object.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>file_or_filename</strong> – Either an already opened file or file-like
object, or a filename to open.</p></li>
<li><p><strong>mode</strong> – The mode to open the file in.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.reset_get_unique_name">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">reset_get_unique_name</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#reset_get_unique_name"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.reset_get_unique_name" title="Link to this definition">¶</a></dt>
<dd><p>Reset the heaps that store previously-assigned names.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.rmv_attr">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">rmv_attr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">objs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attrs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#rmv_attr"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.rmv_attr" title="Link to this definition">¶</a></dt>
<dd><p>Remove a list of attributes from a list of objects.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.rmv_iadd">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">rmv_iadd</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">objs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#rmv_iadd"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.rmv_iadd" title="Link to this definition">¶</a></dt>
<dd><p>Delete iadd_flag attribute from a list of objects.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.rmv_quotes">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">rmv_quotes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#rmv_quotes"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.rmv_quotes" title="Link to this definition">¶</a></dt>
<dd><p>Remove starting and ending quotes from a string.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.set_attr">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">set_attr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">objs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#set_attr"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.set_attr" title="Link to this definition">¶</a></dt>
<dd><p>Set an attribute in a list of objects.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.set_iadd">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">set_iadd</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">objs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#set_iadd"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.set_iadd" title="Link to this definition">¶</a></dt>
<dd><p>Set iadd_flag with T/F value for a list of objects.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.sgn">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">sgn</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#sgn"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.sgn" title="Link to this definition">¶</a></dt>
<dd><p>Return -1,0,1 if x&lt;0, x==0, x&gt;0.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="skidl.utilities.to_list">
<span class="sig-prename descclassname"><span class="pre">skidl.utilities.</span></span><span class="sig-name descname"><span class="pre">to_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/skidl/utilities.html#to_list"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#skidl.utilities.to_list" title="Link to this definition">¶</a></dt>
<dd><p>Return x if it is already a list, or return a list containing x if x is a scalar.</p>
</dd></dl>

</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">skidl.utilities module</a><ul>
<li><a class="reference internal" href="#skidl.utilities.Rgx"><code class="docutils literal notranslate"><span class="pre">Rgx</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.TriggerDict"><code class="docutils literal notranslate"><span class="pre">TriggerDict</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.add_quotes"><code class="docutils literal notranslate"><span class="pre">add_quotes()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.add_unique_attr"><code class="docutils literal notranslate"><span class="pre">add_unique_attr()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.cnvt_to_var_name"><code class="docutils literal notranslate"><span class="pre">cnvt_to_var_name()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.debug_trace"><code class="docutils literal notranslate"><span class="pre">debug_trace()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.expand_buses"><code class="docutils literal notranslate"><span class="pre">expand_buses()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.expand_indices"><code class="docutils literal notranslate"><span class="pre">expand_indices()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.export_to_all"><code class="docutils literal notranslate"><span class="pre">export_to_all()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.filter_list"><code class="docutils literal notranslate"><span class="pre">filter_list()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.find_and_open_file"><code class="docutils literal notranslate"><span class="pre">find_and_open_file()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.find_and_read_file"><code class="docutils literal notranslate"><span class="pre">find_and_read_file()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.find_num_copies"><code class="docutils literal notranslate"><span class="pre">find_num_copies()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.flatten"><code class="docutils literal notranslate"><span class="pre">flatten()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.from_iadd"><code class="docutils literal notranslate"><span class="pre">from_iadd()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.fullmatch"><code class="docutils literal notranslate"><span class="pre">fullmatch()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.get_unique_name"><code class="docutils literal notranslate"><span class="pre">get_unique_name()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.is_binary_file"><code class="docutils literal notranslate"><span class="pre">is_binary_file()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.list_or_scalar"><code class="docutils literal notranslate"><span class="pre">list_or_scalar()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.merge_dicts"><code class="docutils literal notranslate"><span class="pre">merge_dicts()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.norecurse"><code class="docutils literal notranslate"><span class="pre">norecurse()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.num_to_chars"><code class="docutils literal notranslate"><span class="pre">num_to_chars()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.opened"><code class="docutils literal notranslate"><span class="pre">opened()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.reset_get_unique_name"><code class="docutils literal notranslate"><span class="pre">reset_get_unique_name()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.rmv_attr"><code class="docutils literal notranslate"><span class="pre">rmv_attr()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.rmv_iadd"><code class="docutils literal notranslate"><span class="pre">rmv_iadd()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.rmv_quotes"><code class="docutils literal notranslate"><span class="pre">rmv_quotes()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.set_attr"><code class="docutils literal notranslate"><span class="pre">set_attr()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.set_iadd"><code class="docutils literal notranslate"><span class="pre">set_iadd()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.sgn"><code class="docutils literal notranslate"><span class="pre">sgn()</span></code></a></li>
<li><a class="reference internal" href="#skidl.utilities.to_list"><code class="docutils literal notranslate"><span class="pre">to_list()</span></code></a></li>
</ul>
</li>
</ul>

  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/rst_output/skidl.utilities.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">SKiDL 1.2.2 documentation</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">skidl.utilities module</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2016-2024, Dave Vandenbout.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
    </div>
  </body>
</html>